All Databases Inside Mac - AppleEvents

Getting Data Out of an Apple Event

The Apple Event Manager stores the parameters and attributes of an Apple

event in a format that is internal to the Apple Event Manager. You use

Apple Event Manager functions to retrieve the data from an

Apple event and return it to your application in a format your application can

use.

The Apple Event Manager provides functions that retrieve data from

parameters and attributes. Most of these functions are available in two forms:

one that returns the desired data in a specified buffer and one that returns a

descriptor record containing the same data. For example, the

AEGetParamPtr function returns the data of a specified parameter, and the

AEGetParamDesc function returns the descriptor record of a specified

parameter.

You can also use Apple Event Manager functions to get data out of

descriptor records, descriptor lists, and AE records. You use similar

functions to put data into descriptor records, descriptor lists, and

AE records.

When your handler receives an Apple event, you'll typically use the

AEGetParamPtr, AEGetAttributePtr, AEGetParamDesc, or

AEGetAttributeDesc function to get the data out of the Apple event.

Some Apple Event Manager functions let your application request that the

data be returned using any descriptor type, even if it is different from the

original descriptor type. If the original data is of a different

descriptor type, the Apple Event Manager attempts to coerce the data to

the requested descriptor type.

For example, the AEGetParamPtr function lets you specify the desired

descriptor type of the resulting data.

AppleEvent theAppleEvent;

DescType returnedType;

long multResult;

Size actualSize;

OSErr myErr;

myErr = AEGetParamPtr(& theAppleEvent, keyMultResult, typeLongInteger,

& returnedType, (Ptr) &multResult, sizeof(multResult),

& actualSize);

In this example, the desired type is specified in the third parameter by the

typeLongInteger descriptor type. This requests that the

Apple Event Manager coerce the data to the type defined by this

descriptor type (a long integer) if it is not already of this type.

To ensure that no coercion is performed and that the descriptor type of the

result is of the same type as the original, you can specify typeWildCard for the

desired descriptor type.

The Apple Event Manager returns the descriptor type of the resulting data

in the fourth parameter. This is useful information when you specify

typeWildCard as the desired descriptor type; you can determine the

descriptor type of the resulting data by examining the fourth parameter.

The Apple Event Manager can coerce many different types of data into

another. For example, the Apple Event Manager can convert

alias records to file system specification records (FSSpec), integers to

Boolean data types, and characters to numeric data types, in addition to other

data type conversions. See Built-in Coercion Handlers for a list of the

types of coercions that the Apple Event Manager can perform.

You can also provide your own coercion handlers to coerce other data types.

See Writing and Installing Coercion Handlers for more information.

Parameters are keyword-specified descriptor records. You can use

AEGetParamDesc to get the descriptor record of a parameter, or you can

use AEGetParamPtr to get the data out of the descriptor record of a

parameter. Attributes are also keyword-specified descriptor records, and you

can use similar routines to get the descriptor record of an attribute or to get

the data out of an attribute.

Examples of how to use the AEGetParamPtr, AEGetAttributePtr,

AEGetParamDesc, or AEGetAttributeDesc function to get the data out of

an Apple event are included in Getting Data Out of a Parameter and

Getting Data Out of an Attribute.

Referenced by (12):